Supporting QuickDraw GX Print Dialog Boxes(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 2 - Core Printing Features / Using Core Printing Features

Supporting QuickDraw GX Print Dialog Boxes
Dialog boxes for QuickDraw GX printing features are movable modal. A movable modal dialog box is a modal dialog box that contains a title bar by which users can drag the dialog box. This type of dialog box allows users to view windows that would otherwise be obscured by the dialog box. Movable modal dialog boxes are described in Inside Macintosh: Macintosh Toolbox Essentials.
To support QuickDraw GX print dialog boxes, your application needs to identify the Edit menu and its menu items, adjust the menu bar to enable or disable appropriate menu items, and respond to the gxPrintingEvent message that QuickDraw GX sends to your application.
You make menu adjustments just before you display the dialog box. Examples of setting up the menu bar are shown in the sections "Displaying the Page Setup Dialog Box" beginning on page 2-35 and "Displaying the Print Dialog Box" beginning on page 2-37.
This section shows how to set up the override for the gxPrintingEvent message. QuickDraw GX sends this message to your application each time it receives an event, such as a mouse click or a keystroke. Because you want the application to respond to update events so that the window can be redrawn, you must install the application as a handler for the gxPrintingEvent message.
You create a function that has the same prototype (the same format of parameters and return value) as the GXPrintingEvent function and install it in the message chain. To override the gxPrintingEvent message, you specify a pointer to an override function in the GXInstallApplicationOverride function. Because dialog boxes are associated with individual job objects, you must call GXInstallApplicationOverride after you create each job object.
The override persists until you dispose of the job object or install another override for the gxPrintingEvent message. Listing 2-1 on page 2-12 shows the following call in the context of creating a new job object:
GXInstallApplicationOverride(myDocument->documentJob,
                            gxPrintingEvent,
                            MyPrintingEventOverride);
The GXInstallApplicationOverride function has three parameters:

A reference to the job object. In Listing 2-1 on page 2-12, it is the job object that was stored when the document was created.
The ID of the message to override. In this case, it is gxPrintingEvent.
The function that responds to the message. In this case, it is MyPrintingEventOverride.

The parameters to the override function named MyPrintingEventOverride must match those of the GXPrintingEvent message override function, which has the following declaration:
OSErr GXPrintingEvent (EventRecord *anEventRecord,
                        Boolean filterEvent);
The anEventRecord parameter is a pointer to the event record, which contains information about what type of event occurred while the print dialog box was being displayed; for example, a mouse click or key-down. The event record also contains additional information associated with the event, such as which key was pressed for a key-down event.
The filterEvent parameter specifies whether the event can be filtered. QuickDraw GX sends two gxPrintingEvent messages for each event. The first event can be filtered, for example, by calling the DialogSelect function to filter non-update events.

Note
The Window Manager generates update events to control the appearance of windows on the screen. The EventRecord data type, the Window Manager, the DialogSelect function, and update events are discussed in Inside Macintosh: Macintosh Toolbox Essentials.
Listing 2-4 shows an override function for the gxPrintingEvent message.
Listing 2-4 Override function for the gxPrintingEvent message
OSErr MyPrintingEventOverride(EventRecord *anEvent, 
                              Boolean filterEvent)
{
   OSErr    err = noErr;
   
   /* Handle events in whatever way is appropriate.  MyDoEvent 
      is a generic event handler.  Don't pass it events that
      it shouldn't handle while print dialogs are displayed. 
   */
   if (!filterEvent)
      switch (anEvent->what)
      {
         case mouseDown:
         case keyDown:
         case autoKey:
            break;
         
         default:
            err = MyDoEvent(anEvent);
      }
   return err;
}
Note
You do not need to forward the gxPrintingEvent message.
In Listing 2-4, if the event is not a filter event, MyDoEvent is called because the event is probably an update event. The MyDoEvent function is the general-purpose, application-specific function that handles all events and is typically called after each WaitNextEvent. The MyDoEvent function is called from this override to dispatch redrawing of the document's window in response to an update event.